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Validation List APIs 


Validation lists contain entries that consist of an identifier, data that will be encrypted when it is stored, and 
free-form data. Entries can be added, changed, removed, found, and validated. You can validate entries by 
providing the correct entry identifier and data that is encrypted. 


One way to use validation lists is to store the user names of a Web browser. The entry identifier would be 
the user name, the data to encrypt would be the user's password, and the free-form data field would contain 
any additional data about the user that the browser wanted to store. 
The validation list APIs are: 

e Add Validation List Entry (QSYADVLE) adds an entry to a validation list object. 


e Add Validation List Entry (QsyAddValidationLstEntry()) adds an entry to a validation list object. 
e Change Validation List Entry (QS YCHVLE) changes an entry in a validation list object. 


e Change Validation List Entry (QsyChangeValidationLstEntry()) changes an entry in a validation 
list object. 

e Find First Validation List Entry (QsyFindFirstValidationLstEntry() finds the first entry in a 
validation list object and returns information about the validation list entry. 


e Find Next Validation List Entry (QsyFindNextValidationLstEntry()) finds the next entry ina 


validation list object after the entry that is passed in the Entry_ID parameter and returns 
information about the validation list entry. 


e Find Validation List Entry (QSYFDVLE) finds an entry in a validation list object and returns it. 


e Find Validation List Entry (QsyFindValidationLstEntry(Q) finds an entry in a validation list object 
and returns information about the validation list entry. 

e Find Validation List Entry Attributes (QsyFindValidationLstEntryAttrs()) finds an entry in a 
validation list object, and the attributes associated with the entry. 

e Open List of Validation List Entries (QS YOLVLE) returns a list of validation list entries in a 
validation list object. 


e Remove Validation List Entry (QsyRemoveValidationLstEntry()) removes an entry from a 
validation list object. 


e Remove Validation List Entry (QS YRMVLE) removes an entry from a validation list object. 


e Verify Validation List Entry (QsyVerify ValidationLstEntry() verifies an entry in a validation list 
object. 


Top | Security APIs | APIs by category 


Add Validation List Entry (QSYADVLE) API 


Required Parameter Group: 


Qualified validation list name Char(20) 
Entry ID information Char(*) 
Data to encrypt information Char(*) 
Entry data information Char(*) 
Attribute information Char(*) 
Error code Char(*) 


Default Public Authority: *USE 


Threadsafe: Yes 


The Add Validation List Entry (QSYADVLE) API adds an entry to a validation list object. Entries are 
stored in hexadecimal sort sequence. The first entry will always be the one in which the entry ID has the 
smallest hexadecimal value. 


Conversions are not done on any data when entries are added. The CCSID value for each field is stored as 
part of the record but is not used when the entry is added to the validation list. 


Authorities and Locks 


Validation List Object 
*USE and *ADD 
Validation List Object Library 
*EXECUTE 


Required Parameter Group 
Qualified validation list name 
INPUT; CHAR(20) 


The qualified object name of the validation list to add the entry to. The first 10 characters specify 
the validation list name, and the second 10 characters specify the library. 


You can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


Entry ID information 
INPUT; CHAR(*) 


The format of the entry ID information is as follows. See the Field Descriptions for more 
information. 


| Offset 
ae c | Hex |Type Field 


| | [BIN ARY(4) [Length of entry ID 
| >4 | 4 [BINARY (4) |CCSID of entry ID 
| >8 | 8 [CHAR(*) [Entry ID 


Data to encrypt information 
INPUT; CHAR(*) 


Data that is associated with the entry ID and is encrypted by the system when it is stored. 


The format of the data to encrypt information is as follows. See the Field Descriptions for more 
information. 


| Offset 
| Dec | Hex /Type Field 


| 0 | 0 [BIN ARY(4) [Length of data to encrypt 
| 4 | 4 [BIN ARY(4) |CCSID of data to encrypt 
| 8 | 8 |CHAR(*) [Data to encrypt 


Entry data information 
INPUT; CHAR(*) 


Data information that is associated with the entry ID. The format of the entry data information is as 
follows. See the Field Descriptions for more information. 


| Offset 
oe c | Hex |Type Field 


| | [BINARY(4) |Lengthofdata = ist—‘“‘=s~‘“‘“‘~™*” 
= [4 |BINARY(@) |CCSIDofdata | 
[8 | 8 |CHAR® [Daa =Ssstst—“‘S..C;C~™OOSTTTTTTTCS 


Attribute information 
INPUT; CHAR(*) 


Attribute information that is associated with the entry. The format of the attribute information is as 
follows. See the Field Descriptions for more information. 


| Offset 
| Dec Hex |Type Field 


| 0 | 0 [BINARY(4) [Number of attributes 
| 4 | 4 [CHAR(*) [Attribute structures 


The format of the attribute structure is as follows. See the Field Descriptions for more information. 


| Offset 
| D c | Hex ae Field 


For attributes that are stored in the validation list object, the format of the attribute data is as 
follows. See the Field Descriptions for more information. 


| Offset 
| Dec | Hex |Type Field 


Error code 


V/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Field Descriptions 


Attribute data. The information that describes the attribute data. 


Attribute ID. The ID of the attribute. For system-defined attributes, the allowed values are: 


| String value Description 
| QsyEncryptData | This is the attribute that is associated with the data to encrypt. 


Attribute location. Where the attribute should be stored. 


The allowed value is: 


0 The attribute is stored in the validation list object. 


Attribute structures. Zero or more attribute structures that define the attributes to be associated with the 
entry. 


Attribute type. The type of attribute. 
The allowed value follows: 


0 This is a system-defined attribute. 


Attribute value. The value of the attribute that is associated with the entry. 
For the QsyEncryptData attribute, the allowed values follow: 
0 The data to be encrypted can only be used to verify an entry. This is the default. 


1 The data to be encrypted can be used to verify an entry and can be returned on a find operation. The 
system value QRETSVRSEC (Retain server security data) is used to determine if the data to be 
encrypted is stored in the entry or not. 


If the system value is set to 0 (Do not retain data), the entry will be added, but the data to be 
encrypted will not be stored with the entry. The return value from this function will be -2 to indicate 
that the entry was added, but the data to be encrypted was not stored. 


If the system value is set to 1 (Retain data), then the data to be encrypted will be stored in encrypted 
form when the entry is added. 


CCSID of attribute. An integer that represents the CCSID for the attribute. Valid CCSID values are in the 
range -1 through 65535. 


The special values follow: 


-1 No CCSID value is stored with the attribute. If the attribute is QsyEncryptData, this value must be 
specified. 


O The default CCSID for the current user is stored. 


CCSID of data to encrypt. An integer that represents the CCSID for the data to encrypt. Valid CCSID 
values are in the range 1 through 65535. 


The special value follows: 


O The default CCSID for the current user is stored. 


CCSID of data. An integer that represents the CCSID for the entry data. Valid CCSID values are in the 
range | through 65535. 


The special value follows: 


O The default CCSID for the current user is stored. 


CCSID of entry ID. An integer that represents the CCSID for the entry ID. Valid CCSID values are in the 
range | through 65535. 


The special value follows: 


O The default CCSID for the current user is stored. 


Data. The data to store in the validation list entry. 
Data to encrypt. The data to be encrypted before storing it in the validation list entry. 


Displacement to attribute data. The displacement in the attribute entry to the start of the attribute data 
information. 


Displacement to attribute ID. The displacement in the attribute entry to the start of the attribute ID value. 
Entry ID. The data that is used to identify this entry in the validation list. 


Length of attribute. The number of bytes of data in the attribute value. The length must be greater than 0. 
For the QsyEncryptData attribute, the length must be 1. 


Length of attribute data. The number of bytes of data in the attribute data structure. The length must be 
greater than 0. 


Length of attribute entry. The length (in bytes) of the current entry. This length can be used to access the 
next entry, and must be a multiple of 4. 


Length of attribute ID. The number of bytes of data in the attribute ID. The length must be greater than 0. 


Length of data to encrypt. The number of bytes of data to be encrypted and stored in this validation list 
entry. Possible values are 0 through 600. If the length is 0, no encrypted data will be stored in the entry. 


Length of data. The number of bytes of data to be stored in this validation list entry. Possible values are 0 
through 1000. If the length is 0, no data will be stored in the entry. 


Length of entry ID. The number of bytes of data that is provided as the entry ID. Possible values are 1 
through 100. 


Number of attributes. The number of attributes to be added. This value must be greater than or equal to 0. 
If this value is 0, then no attributes will be added to the entry. 


Reserved. This is an ignored field. 


Error Messages 


Message ID Error Message Text 

CPFAOAA E Error occurred while attempting to obtain space. 
CPF226A E Validation list entry already exists. 

CPF226D E Not all information stored. 

CPF3CF1 E Error code parameter not valid. 

CPF3C36 E Number of parameters, &1, entered for this API was not valid. 
CPF3C90 E Literal value cannot be changed. 

CPF9801 E Object &2 in library &3 not found. 

CPF9802 E Not authorized to object &2 in &3. 

CPF9803 E Cannot allocate object &2 in library &3. 
CPF9804 E Object &2 in library &3 damaged. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


API Introduced: V4R1 


Top | Security APIs | APIs by category 


QsyAddValidationLstEntry()--Add Validation 
List Entry API 


Syntax 


#include <qsyvldl.h> 


int QsyAddValidationLstEntry 
(Qsy_Qual_Name_T *Validation_Lst, 
Qsy_Entry_ID_Info_T *Entry_ID, 
Qsy_Entry_Encr_Data_Info_T *Encrypt_Data, 
Qsy_Entry_Data_Info_T *Entry_Data, 
void *Attribute_Info); 


Service Program Name: QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsyAddValidationLstEntry() function adds an entry to a validation list object. Entries are stored in 
hexadecimal sort sequence. The first entry will always be the one in which the entry ID has the smallest 
hexadecimal value. 


Conversions are not done on any data when entries are added. The CCSID value for each field is stored as 
part of the record but is not used when the entry is added to the validation list. 


Authorities 


Validation List Object 
*USE and *ADD 


Validation List Object Library 
*EXECUTE 


Parameters 


Validation_Lst 


(Input) A pointer to the qualified object name of the validation list to add the entry to. The first 10 
characters specify the validation list name, and the second 10 characters specify the library. You 
can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


Entry_ID 
(Input) A pointer to the entry ID information. The format of the Qsy_Entry_ID_Info_T structure is 
as follows: 
int Entry_ID_Len The number of bytes of data that is provided as the entry 


ID. Possible values are from 1 through 100. 


unsigned int Entry_ID_CCSID An integer that represents the CCSID for the entry ID. 
Valid CCSID values are in the range 1 through 65535. The 
special value follows: 


O The default CCSID for the current user is stored. 


unsigned char Entry_ID[] The data that is used to identify this entry in the validation 
list. 


Encrypt_Data 


(Input) A pointer to data that is associated with the entry ID and is encrypted by the system when it 
is stored. If the pointer is NULL, there is no encrypted data associated with the entry ID. The 
format of the Qsy_Entry_Encr_Data_Info_T structure is as follows: 


int Encr_Data_Len The number of bytes of data to be encrypted and stored in 
this validation list entry. Possible values are from 1 
through 600. 


unsigned int | Encr_Data_CCSID An integer that represents the CCSID for the data to 
encrypt. Valid CCSID values are in the range | through 
65535. The special value follows: 


O The default CCSID for the current user is stored. 


unsigned char Encr_Data[] The data to be encrypted before storing it in the validation 
list entry. 


Entry_Data 


(Input) A pointer to the data information that is associated with the entry ID. If the pointer is 
NULL, there is no data associated with the entry ID. The format of the Qsy_Entry_Data_Info_T 
structure is as follows: 


int Entry_Data_Len The number of bytes of data to be stored in this validation 
list entry. Possible values are from 1 through 1000. 


unsigned int Entry_Data_CCSID An integer that represents the CCSID for the data. Valid 
CCSID values are in the range 1 through 65535. The 
special value follows: 


O The default CCSID for the current user is stored. 


unsigned char Entry_Data[] The data to be stored in the validation list entry. 


Attribute_Info 


(Input) A pointer to a structure that contains attribute information that is associated with the entry 
ID. If the pointer is NULL, there is no attribute information associated with the entry ID. The 
format of the Qsy_Attr_Info_T structure is as follows: 


int Number_Attrs The number of attributes being added. This value must be 
greater than 0. 


char Res_Align[12] Reserved for boundary alignment. 


Qsy_Attr_Descr_T Attr_Descr[] An array of attribute description structures. 


The format of the Qsy_Attr_Descr_T structure is as follows: 


int Attr_Location Where the attribute should be stored. The allowed value 
follows: 


0 QOSY_IN_VLDL The attribute is stored in the 
validation list object. 


int Attr_Type The type of attribute. The allowed value follows: 


0 OQSY_SYSTEM_ATTR This is a system-defined 


attribute. 
union Attr_Res Res_1[8] Reserved data. This value must be hexadecimal zero. 
char * Attr_ID The ID of the attribute. For system-defined attributes, the 
allowed value is: 
String value Description 


QsyEncryptData This is the attribute that is associated 
with the data to encrypt. 


union Attr_Other_Descr Reserved data. This value must be hexadecimal zero. 
Res_1[32] 


union Attr_Data_Info The information describing the attribute data. 


union Attr_Other_Data Reserved data. This value must be hexadecimal zero. 
Res_1[32] 


The format of the Attr_Data_Info union is as follows: 


Qsy_In_VLDL_T Attr_VLDL The attribute data information for an attribute 
that is stored in the validation list object. 


union Attr_In_Other Res_1[96] Reserved data. The last 64 bytes must be zero. 


The format of the Qsy_In_VLDL_T structure is as follows: 


int Attr_CCSID An integer that represents the CCSID for the attribute. Valid 
CCSID values are in the range -1 through 65535. The special 
values follow: 


-I No CCSID value is stored with the attribute. If the attribute 
is QsyEncryptData, this value must be specified. 


O The default CCSID for the current user is stored. 


int Attr_Len The number of bytes of data in the attribute value. The length must 
be greater than 0. For the QsyEncryptData attribute, the length 
must be 1. 


union Attr_Res Res_1[8] Reserved data. This value must be hexadecimal zero. 


void * Attr_Value A pointer to the value of the attribute associated with the entry. 
For the QsyEncryptData attribute, the allowed values follow: 


0 QSY_VFY_ONLY The data to be encrypted can only be used 
to verify an entry. This is the default. 


I QSY_VFY_FIND _ The data to be encrypted can be used to 
verify an entry and can be returned on a 
find operation. 


If the QSY_VFY_FIND value is specified for the QsyEncryptData attribute, the system value 
QRETSVRSEC (Retain server security data) is used to determine if the data to be encrypted is stored in the 
entry or not. 


If the system value is set to 0 (Do not retain data), the entry will be added, but the data to be encrypted will 
not be stored with the entry. The return value from this function will be -2 to indicate that the entry was 
added, but the data to be encrypted was not stored. 


If the system value is set to 1 (Retain data), then the data to be encrypted will be stored when the entry is 
added. 


Return Value 
O QsyAddValidationLstEntry() was successful. 


-1 QsyAddValidationLstEntry() was not successful. The errno global variable is set to indicate the 
error. 


-2. QsyAddValidationLstEntry() was successful, but the data to be encrypted was not stored. 


Error Conditions 


If QsyAddValidationLstEntry() is not successful, errno indicates one of the following errors: 
3401 [EACCES] 


The current user does not have *USE and *ADD authorities to the validation list object, or does 
not have *EXECUTE authority to the validation list object library. 


3406 [EAGAIN] 

The validation list object is currently locked by another process. 
3484 [EDAMAGE] 

The validation list object is damaged. 
3457 [EEXIST] 

Specified entry already exists. 
3021 [EINVAL] 

Parameter value is not valid. 
3025. [ENOENT] 

The validation list object was not found. 
3404 [ENOSPC] 

No space available. 
3474. [EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. 


Example 


See Code disclaimer information for information pertaining to code examples. 


The following example adds an entry for a user named FRED to the validation list object WEBUSRS. 
FRED has encrypted data (password), but no other data. The CCSID for the entry ID is set to the current 
user's default CCSID. The CCSID for the encryption data is set to 65535. 


#include <qsyvldl.h> 


main () 

{ 
#define VLD_LST "WEBUSRS WEBLIB iH 
Qsy_Entry_ID_Info_T entry_info; 
Qsy_Entry_Encr_Data_Info_T encrypt_data; 


entry_info.Entry_ID_Len = 4; 

entry_info.Entry_ID_CCSID = 0; 

strncpy (entry_info.Entry_ID, "FRED", entry_info.Entry_ID_Len); 

encrypt_data.Encr_Data_Len = 7; 

strncpy (encrypt_data.Encr_Data,"N1LJDTS", 
encrypt_data.Encr_Data_Len) ; 

encrypt_data.Encr_Data_CCSID = 65535; 


if (0 != QsyAddValidationLstEntry((Qsy_Qual_Name_T *)&VLD_LST, 
é&éentry_info, 
é&éencrypt_data, 
NULL, 
NULL) ) 
perror ("QsyAddValidationLstEntry()"); 


API introduced: V4R1 
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Change Validation List Entry (QSYCHVLE) API 


Required Parameter Group: 


Qualified validation list name Char(20) 
Entry ID information Char(*) 
Data to encrypt information Char(*) 
Entry data information Char(*) 
Attribute information Char(*) 
Error code Char(*) 


Default Public Authority: *USE 


Threadsafe: Yes 


The Change Validation List Entry (QS YCHVLE) API changes an entry in a validation list object. The data 
to be encrypted, the entry data values, and some of the entry attributes may be changed. 


To identify an entry to be changed, there must be an exact match in the entry for the value that is specified 
in the entry ID parameter and the length of the entry ID. For example, an entry ID value of SMITH with a 
length of 5 would not allow you to change an entry where the entry ID is SMITH and the length is 7. 


Conversions are not done on any data when entries are changed. The CCSID values for the fields are stored 
as part of the record but are not used when the entry is changed. 


Authorities and Locks 


Validation List Object 
*USE and *UPD 
Validation List Object Library 
*EXECUTE 


Required Parameter Group 
Qualified validation list name 
INPUT; CHAR(20) 


The qualified object name of the validation list that contains the entry to change. The first 10 
characters specify the validation list name, and the second 10 characters specify the library. 


You can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


Entry ID information 
INPUT; CHAR(*) 


The format of the entry ID information is as follows. See the Field Descriptions for more 
information. 


| Offset 
oe c | Hex |Type Field 


| | [BIN ARY(4) [Length of entry ID 
| 4 | 4 [BINARY (4) |CCSID of entry ID 
| 8 | 8 [CHAR(*) [Entry ID 


Data to encrypt information 
INPUT; CHAR(*) 


The data is encrypted by the system when it is stored. The format of the data to encrypt information 
is as follows. See the Field Descriptions for more information. 


| Offset 
| Dec | Hex Type Field 


| 0 | 0 [BIN ARY(4) [Length of data to encrypt 
| 4 | 4 [BIN ARY(4) |CCSID of data to encrypt 
| 8 | 8 |CHAR(*) [Data to encrypt 


Entry data information 
INPUT; CHAR(*) 


The format of the entry data information is as follows. See the Field Descriptions for more 
information. 


| Offset 
a c | Hex |Type Field 


co; B) Oo] oO 


Attribute information 
INPUT; CHAR(*) 


Attribute information that is associated with the entry. The format of the attribute information is as 


follows. See the Field Descriptions for more information. 


| Offset 
| Dec | Hex /Type Field 


| 0 | 0 [BINARY (4) [Length of data to encrypt 
| 0 | 0 [BIN ARY(4) [N umber of attributes 
| 4 | 4 |CHAR(*) [Attribute structures 


| Offset 
| Dec | Hex Type Field 


| 0 | 0 [BINARY(4) [Length of attribute entry 

| 4 | 4 BINARY(4) [Attribute location 

| 8 | 8 [BIN ARY(4) [Attribute type 

| 12 | C [BINARY(4) [Displacement to attribute ID 

| 16 | 10 |BINARY(4) [Length of attribute ID 

| 20 | 14 [BIN ARY(4) [Displacement to attribute data 
| 24 18 [BINARY (4) [Length of attribute data 
[CHAR(*) [Attribute ID 

|CHAR(*) [Attribute data 


For attributes that are stored in the validation list object, the format of the attribute data is as 
follows. See the Field Descriptions for more information. 


| Offset 
ae c | Hex |Type Field 


[8 | 8 |CHAR® [Reserved SS 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Field Descriptions 


Attribute data. The information that describes the attribute data. 
Attribute ID. The ID of the attribute. 


For system-defined attributes, the allowed value is: 


| String value Description 
| QsyEncryptData | This is the attribute that is associated with the data to encrypt. This attribute can 


only be changed if the length of data to encrypt is not -1. 


Attribute location. Where the attribute should be stored. 
The allowed value is: 


0 The attribute is stored in the validation list object. 


Attribute structures. Zero or more attribute structures that define the attributes associated with the entry. 
Attribute type. The type of attribute. 
The allowed value follows: 


0 This is a system-defined attribute. 


Attribute value. The value of the attribute that is associated with the entry. 
For the QsyEncryptData attribute, the allowed values follow: 

0 The data to be encrypted can only be used to verify an entry. This is the default. 

I The data to be encrypted can be used to verify an entry and can be returned on a find operation. The 
system value QRETSVRSEC (Retain server security data) is used to determine if the data to be 
encrypted is stored in the entry or not. 

If the system value is set to 0 (Do not retain data), the entry will be added, but the data to be 
encrypted will not be stored with the entry. The return value from this function will be -2 to indicate 


that the entry was added, but the data to be encrypted was not stored. 


If the system value is set to 1 (Retain data), then the data to be encrypted will be stored in encrypted 
form when the entry is added. 


CCSID of attribute. An integer that represents the CCSID for the attribute. Valid CCSID values are in the 
range -1 through 65535. 


The special values follow: 


-1 No CCSID value is stored with the attribute. If the attribute is QsyEncryptData, this value must be 
specified. 


O The default CCSID for the current user is stored. 


CCSID of data to encrypt. An integer that represents the CCSID for the data to encrypt. Valid CCSID 
values are in the range 1 through 65535. 


The special value follows: 


O The default CCSID for the current user is stored. 


CCSID of data. An integer that represents the CCSID for the entry data. Valid CCSID values are in the 
range | through 65535. 


The special value follows: 


O The default CCSID for the current user is stored. 


CCSID of entry ID. An integer that represents the CCSID for the entry ID. Valid CCSID values are in the 
range 0 through 65535. This field is not used to change the entry. 


Data. The data to store in the validation list entry. 
Data to encrypt. The data to be encrypted before storing it in the validation list entry. 


Displacement to attribute data. The displacement in the attribute entry to the start of the attribute data 
information. 


Displacement to attribute ID. The displacement in the attribute entry to the start of the attribute ID value. 
Entry ID. The data that is used to identify this entry in the validation list. 


Length of attribute. The number of bytes of data in the attribute value. The length must be greater than or 
equal to 0. If a length of 0 is specified, the attribute is removed from the entry. For the QsyEncryptData 
attribute, the maximum length is 1. 


Length of attribute data. The number of bytes of data in the attribute data structure. The length must be 
greater than 0. 


Length of attribute entry. The length (in bytes) of the current entry. This length can be used to access the 
next entry, and must be a multiple of 4. 


Length of attribute ID. The number of bytes of data in the attribute ID. The length must be greater than 0. 


Length of data to encrypt. The number of bytes of data to be encrypted and stored in this validation list 
entry. Possible values are -1 through 600. If the length is 0, any encrypted data that is associated with the 
entry ID will be removed. If the length is -1, the encrypted data that is associated with the entry ID is not 
changed. 


Length of data. The number of bytes of data to be stored in this validation list entry. Possible values are -1 
through 1000. If the length is 0, any data that is associated with the entry ID will be removed. If the length 
is -1, the data that is associated with the entry ID is not changed. 


Length of entry ID. The number of bytes of data that is provided as the entry ID. Possible values are 1 
through 100. 


Number of attributes. The number of attributes to be added. This value must be greater than or equal to 0. 
If this value is 0, then no attributes will be changed in the entry. 


Reserved. This is an ignored field. 


Error Messages 


Message ID Error Message Text 

CPFAOAA E Error occurred while attempting to obtain space. 
CPF226B E Validation list entry does not exist. 

CPF226D E Not all information stored. 

CPF3CF1 E Error code parameter not valid. 

CPF3C36 E Number of parameters, &1, entered for this API was not valid. 
CPF3C90 E Literal value cannot be changed. 

CPF9801 E Object &2 in library &3 not found. 

CPF9802 E Not authorized to object &2 in &3. 

CPF9803 E Cannot allocate object &2 in library &3. 
CPF9804 E Object &2 in library &3 damaged. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 


API Introduced: V4R2 


Top | Security APIs | APIs by category 


QsyChangeValidationLstEntry()--Change 
Validation List Entry API 


Syntax 


#include <qsyvldl.h> 


int QsyChangeValidationLstEntry 
(Qsy_Qual_Name_T *Validation_Lst, 
Qsy_Entry_ID_Info_T *Entry_ID, 
Qsy_Entry_Encr_Data_Info_T *Encrypt_Data, 
Qsy_Entry_Data_Info_T *Entry_Data, 
void *Attribute_Info); 


Service Program Name: QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsyChangeValidationLstEntry() function changes an entry in a validation list object. The data to be 
encrypted, the entry data values, and some of the entry attributes may be changed. 


To identify an entry to be changed, there must be an exact match in the entry for the value that is specified 
in the Entry_ID parameter and the length of the entry ID. For example, an entry ID value of "SMITH" with 
a length of 5 would not allow you to change an entry where the entry ID is "SMITH" and the length is 7. 


Conversions are not done on any data when entries are changed. The CCSID values are stored as part of the 
record, to be available to the user of the API, but are not used when the entry is changed. 


Authorities 


Validation List Object 
*USE and *UPD 


Validation List Object Library 
*EXECUTE 


Parameters 


Validation_Lst 
(Input) 


A pointer to the qualified object name of the validation list that contains the entry to change. The 


first 10 characters specify the validation list name, and the second 10 characters specify the library. 
You can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 
Entry_ID 


(Input) 


A pointer to the entry ID information. The Qsy_Entry_ID_Info_T structure is as follows: 


int Entry_ID_Len The number of bytes of data that is provided as the entry 
ID. Possible values are from 1 through 100. 

unsigned int Entry_ID_CCSID | An integer that represents the CCSID for the entry ID. 
Valid CCSID values are in the range 0 through 65535. 
This field is not used to change the entry. 


unsigned char | Entry_ID[] The data that is used to identify this entry in the validation 
| | | list. 


Encrypt_Data 
(Input) 


A pointer to the data that is associated with the entry ID. The data is encrypted by the system when 
it is stored. If the pointer is NULL, the encrypted data that is associated with the entry ID is not 
changed. The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows: 


int Encr_Data_Len 


unsigned int Encr_Data_CCSID | An integer that represents the CCSID for the data to 
encrypt. Valid CCSID values are in the range 1 through 
65535. The special value follows: 


The number of bytes of data to be encrypted and stored 
in this validation list entry. Possible values are from 0 
through 600. 


0 The default CCSID for the current user is stored. 


unsigned char | Encr_Data[] The data to be encrypted before storing it in the 
validation list entry. 


If Encr_Data_Len is 0, any encrypted data that is associated with the entry ID will be removed. 
Entry_Data 
(Input) 


A pointer to the data information that is associated with the entry ID. If the pointer is NULL, the 
data that is associated with the entry ID is not changed. The format of the Qsy_Entry_Data_Info_T 


structure is as follows: 


int Entry_Data_Len 


unsigned int Entry_Data_CCSID 


The number of bytes of data to be stored in this 
validation list entry. Possible values are from 0 through 
1000. 


An integer that represents the CCSID for the data. Valid 
CCSID values are in the range 1 through 65535. The 
special value follows: 


0 The default CCSID for the current user is stored. 


| unsigned char | Entry_Data[] | The data to be stored in the validation list entry. 


If the Entry_Data_Length is 0, any data that is associated with the entry ID will be removed. 
Attribute_Info 


(Input) 
A pointer to a structure that contains attribute information that is associated with the entry ID. If the 


pointer is NULL, the attributes associated with the entry ID are not changed. The format of the 
Qsy_Attr_Info_T structure is as follows: 


Number_Attrs | The number of attributes being changed. This value 
must be greater than 0. 
7 char | Res_Align[12] | Reserved for boundary alignment. for | Reserved for boundary alignment. alignment. 
| Qsy_Attr_Descr_T | Attr_Descr[] | An array of attribute description structures. 


The format of the Qsy_Attr_Descr_T structure is as follows: 


int Attr_Location 
int Attr_Type The type of attribute. The allowed value follows: 
0 OSY_SYSTEM_ATTR This is a system-defined 
attribute. 


| union | Attr_Res Res_1[8] | Reserved data. This value must be hexadecimal zero, data. This value | Reserved data. This value must be hexadecimal zero, be hexadecimal zero. 


char * | Attr_ID The ID of the attribute. For system-defined attributes, the 
allowed value is: 


| | String value [Description 


Where the attribute should be stored. The allowed value 
follows: 


0 QSY_IN_VLDL The attribute is stored in the 
validation list object. 


This is the attribute that is associated with the data to 
encrypt. This attribute can only be changed if the 
Encrypt_Data parameter is not NULL. 


union | Attr_Other_Descr Reserved data. This value must be hexadecimal zero. 
Res_1[32] 


| union | Attr_Data_Info | The information that describes the attribute data, information that describes the attribute data. 
union | Attr_Other_Data Reserved data. This value must be hexadecimal zero. 
Res_1[32] 


The format of the Attr_Data_Info_T union is as follows: 


Qsy_In_VLDL_T |} Attr_VLDL The attribute data information for an attribute 
that is stored in the validation list object. 


| union | Attr_In_Other Res_1[96] | Reserved data. The last 64 bytes must be 2er0. data. The last 64 | Reserved data. The last 64 bytes must be 2er0. must be zero. 


QsyEncryptData 


The format of the Qsy_In_VLDL_T structure is as follows: 


int Attr_CCSID 


i Attr_Len 


| union | Attr_Res Res_1[8] | Reserved data. This value must be hexadecimal zero. 


void * | Attr_Value 


If the QSY_VFY_FIND value is specified for the QsyEncryptData attribute, the system value 


An integer that represents the CCSID for the attribute. Valid 
CCSID values are in the range -1 through 65535. The special 
values follow: 


-I_ NoCCSID value is stored with the attribute. If the 
attribute is QsyEncryptData, this value is assumed. 


O The default CCSID for the current user is stored. 


The number of bytes of data in the attribute value. The length 
must be greater than or equal to 0. If a length of 0 is specified, 
the attribute is removed from the ea For the QsyEncryptData 
attribute, the maximum length is 1 


Pointer to the value of the attribute associated with the entry. For 
the QsyEncryptData attribute, the allowed values follow: 


0 QSY_VFY_ONLY The data to be encrypted can only be 
used to verify an entry. This is the 
default. 


I QSY_VFY_FIND _ The data to be encrypted can be used to 
verify an entry and can be returned on a 
find operation. 


QRETSVRSEC (Retain server security data) is used to determine if the data to be encrypted is 
stored in the entry or not. If the system value is set to 0 (Do not retain data), the entry will be 
changed, but the data to be encrypted will not be stored with the entry. The return value from this 
function will be -2, to indicate that the entry was changed, but the data to be encrypted was not 
stored. If the system value is set to 1 (Retain data), then the data to be encrypted will be stored 
when the entry is changed. 


Return Value 


O QsyChangeValidationLstEntry() was successful. 


-1 QsyChangeValidationLstEntry( was not successful. The errno global variable is set to indicate 
the error. 


-2. QsyChangeValidationLstEntry() was successful, but the data to be encrypted was not stored. 


Error Conditions 


If QsyChangeValidationLstEntry() is not successful, errno indicates one of the following errors. 
340] [EACCES] 


The current user does not have *USE and *UPD authorities to the validation list object, 
or does not have *EXECUTE authority to the validation list object library. 


3406 [EAGAIN] 

The validation list object is currently locked by another process. 
3484<</em> [EDAMAGE] 

The validation list object is damaged. 
3021 [EINVAL] 

Parameter value is not valid. 
3025 [ENOENT] 

The validation list object was not found. 
3026 [ENOREC] 

Specified entry does not exist. 
3404 [ENOSPC] 

No space available. 
3474 [EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. 


Example 


The following example changes an entry for a user named FRED in the validation list object WEBUSRS. 
FRED's encrypted data (password) and the CCSID for the encrypted data are being changed, but not any 
other data. 


#include <qsyvldl.h> 


main () 

{ 
#define VLD_LST "WEBUSRS WEBLIB v 
Qsy_Entry_ID_Info_T entry_info; 
Qsy_Entry_Encr_Data_Info_T encrypt_data; 


entry_info.Entry_ID_Len = 4; 

strncpy (entry_info.Entry_ID, "FRED", entry_info.Entry_ID_Len); 

encrypt_data.Encr_Data_Len = 7; 

encrypt_data.Encr_Data_CCSID = 37; 

strncpy (encrypt_data.Encr_Data,"MSN1TJG", 
encrypt_data.Encr_Data_Len) ; 


if (0 != QsyChangeValidationLstEntry ( 
(Qsy_Qual_Name_T *) &VLD_LST, 
é&entry_info, 
é&encrypt_data, 
NULL, 
NULL) ) 
perror ("QsyChangeValidationLstEntry()"); 


API introduced: V4R1 


Top | Security APIs | APIs by category 


QsyFindFirstValidationLstEntry()--Find First 
Validation List Entry API 


Syntax 


#include <qsyvldl.h> 


int QsyFindFirstValidationLstEntry 
(Qsy_Qual_Name_T *Validation_Lst, 
Qsy_Rtn_Vld_Lst_Ent_T *First_Entry); 


Service Program Name: QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsyFindFirstValidationLstEntry() function finds the first entry in a validation list object. The 
function then returns the information for the first entry in the buffer that is pointed to by the First_Entry 
parameter. The entries are stored in hexadecimal sort sequence, so the first entry will be the one where the 
entry ID has the smallest hexadecimal value. 


Authorities 


Validation List Object 
*USE 
Validation List Object Library 
*EXECUTE 
Note: If the QsyEncryptData attribute is set to QSY_VWFY_FIND_E (1), then the user must have *USE, 


*ADD, and *UPD authority to the validation list to get the data to be encrypted returned in the First_Entry 
parameter. 


Parameters 


Validation_Lst 
(Input) 


A pointer to the qualified object name of the validation list to find the first entry in. The first 10 
characters specify the validation list name, and the second 10 characters specify the library. You 
can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


First_Entry 
(Output) 


A pointer to the buffer where the first entry information is placed. The buffer must be allocated to 
the size of the Qsy_Rtn_VId_Lst_Ent_T structure or the results will be unpredictable. 


The format of the Qsy_Rin_Vld_Lst_Ent_T structure is as follows: 


Qsy_Entry_ID_Info_T | Entry_ID_Info | The entry ID information structure. 


Qsy_Entry_Encr_Data_Info_T | Encr_Data_Info The data to be encrypted information 
structure. 


Qsy_Entry_Data_Info_T | Entry_Data_Info | The entry data information structure. 
| char | Reserved[4] | This is an ignored field. 


void * Entry_More_Info | A pointer to additional information. This 
pointer is currently set to NULL. 
The format of the Qsy_Entry_ID_Info_T structure is as follows: 
| int | Entry_ID_Len | The length of the entry ID. 


| unsigned int | Entry_ID_CCSID | The CCSID associated with the entry ID. 
| unsigned char | Entry_ID[100] | The entry ID. 


The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows: 
is 0 or the QRETSVRSEC system value is '0'", the length 


int Encr_Data_Len 
will always be 0.%& 


| unsigned int | Encr_Data_CCSID | The CCSID associated with the encrypted data. 


The number of bytes of encrypted data that is stored in 
this validation list entry. If the QsyEncryptData attribute 


unsigned char | Encr_Data[600] Hef the QsyEncryptData attribute is 1 and the 
QRETSVRSEC system value is '1', then the encrypted 
data that is stored in the entry will be decrypted and 
returned in this field. If the QsyEncryptData attribute is 


0 or the QRETSVRSEC system value is '0', then the 
encrypted data cannot be returned, and the contents of 
this field are unpredictable. 


The format of the Qsy_Entry_Data_Info_T structure is as follows: 


| int | Entry_Data_Len | The length of the entry data. 
| unsigned int | Entry_Data_CCSID | The CCSID associated with the entry data. 
| unsigned char | Entry_Data[ 1000] | The entry data. 


Return Value 


O  QsyFindFirstValidationLstEntry() was successful. The return value points to the entry. 


-1 QsyFindFirstValidationLstEntry() was not successful. The errno global variable is set to indicate the 
error. 


Error Conditions 


If QsyFindFirstValidationLstEntry() is not successful, errno indicates one of the following errors: 


3401 


3406 


3484 


3021 


3025 


3026 


3474 


[EACCES] 


The current user does not have *USE authority to the validation list object, or does not have 
*EXECUTE authority to the validation list object library. 


[EAGAIN] 

The validation list object is currently locked by another process. 
[EDAMAGE] 

The validation list object is damaged. 
[EINVAL] 

Parameter value is not valid. 

[ENOENT] 

The validation list object was not found. 
[ENOREC] 

There are no entries in the validation list object. 
[EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. 


Example 


The following example finds all the entries in the validation list object WEBUSRS. 


#include <qsyvldl.h> 
#include <errno.h> 


main () 


{ 


#define VLD_LST "WEBUSRS WEBLIB " 
Qsy_Rtn_Vld_Lst_Ent_T entry_1l; 
Qsy_Rtn_Vld_Lst_Ent_T entry_2; 
Qsy_Rtn_Vld_Lst_Ent_T *input_info, 
*output_info, 


*temp; 
Qsy_Entry_ID_Info_T *input_entry; 
short int ale 
int rtn_errno; 


/* Initialize pointers to input and output buffers. 

output_info = addr(entry_1); 

input_info = addr(entry_2); 

/* Get the first entry in the validation list. 

rtn_errno = QsyFindFirstValidationLstEntry ( 
(Qsy_Qual_Name_T *) &VLD_LST, 
output_info) ) 


while (0 == rtn_errno) 
{ /* Process all the entries in the validation list. 


(process the entry) 


/* Switch the pointers to the buffers so that the output from 
/* the last find operation is used as input to the 'find-next' 
/* operation. 

temp = output_info; 

output_info = input_info; 

input_info = temp; 


/* Find the next entry. 

rtn_errno = QsyFindNextValidationLstEntry ( 
(Qsy_Qual_Name_T *)&VLD_LST, 
&input_info->Entry_ID_Info, 
output_info) ) 


} 

/* Check if an error occurred. 

if (O != rtn_errno && ENOREC != errno) 
perror("Find of validation list entry"); 


API introduced: V4R1 


Top | Security APIs | APIs by category 


QsyFindNextValidationLstEntry()--Find Next 
Validation List Entry API 


Syntax 


#include <qsyvldl.h> 


int QsyFindNextValidationLstEntry 
(Qsy_Qual_Name_T *Validation_Lst, 
Qsy_Entry_ID_Info_T *Entry_ID, 
Qsy_Rtn_Vld_Lst_Ent_T *Next_Entry); 


Service Program Name: QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsyFindNextValidationLstEntry() function finds the next entry in a validation list object after the 
entry that is passed in the Entry_ID parameter. It then returns the information for the next entry in the 
buffer that is pointed to by the Next_Entry parameter. The entries are stored in hexadecimal sort sequence; 
therefore, the next entry will be the one with an entry ID whose hexadecimal value would follow the 
hexadecimal value of the entry passed in the Entry_ID parameter. The entry specified in the Entry_ID 
parameter does not need to exist in the validation list, and this function does not have to follow a 
QsyFindFirstValidationLstEntry() or QsyFindValidationLstEntry() function call. 


Authorities 


Validation List Object 
*USE 


Validation List Object Library 
*EXECUTE 


Note: If the QsyEncryptData attribute is set to QSY_VWFY_FIND_E (1), then the user must have *USE, 
*ADD, and *UPD authority to the validation list to get the data to be encrypted returned in the Next_Entry 
parameter. 


Parameters 


Validation_Lst 
(Input) 


A pointer to the qualified object name of the validation list to find the next entry in. The first 10 
characters specify the validation list name, and the second 10 characters specify the library. You 
can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 
Entry_ID 


(Input) 


A pointer to the entry ID information. The format of the Qsy_Entry_ID_Info_T structure is as 
follows: 


int Entry_ID_Len The number of bytes of data that is provided as the entry 
ID. Possible values are from 1 through 100. 

unsigned int Entry_ID_CCSID | An integer that represents the CCSID for the entry ID. 
Valid CCSID values are in the range 0 through 65535. 
This value is not used to find the entry. 


| unsigned char | Entry_ID[100] 


Next_Entry 
(Output) 


The data that is used to identify this entry in the validation 
list. 


A pointer to the buffer where the next entry information is placed. The buffer must be allocated to 
the size of the Qsy_Rtn_Vid_Lst_Ent_T structure or the results will be unpredictable. The format of 
the Qsy_Rtn_Vld_Lst_Ent_T structure is as follows: 


Qsy_Entry_ID_Info_T Entry_ID_Info | The entry ID information structure. 


Qsy_Entry_Encr_Data_Info_T |} Encr_Data_Info The data to be encrypted information 
structure. 


Qsy_Entry_Data_Info_T Entry_Data_Info | The | The entry data information structure. | The entry data information structure. information structure. 
| char Reserved[4] | This is an ignored field, is an | This is an ignored field, field. 


void * Entry_More_Info | A pointer to additional information. This 
pointer is currently set to NULL. 


See the Entry_ID parameter for the format of the Qsy_Entry_ID_Info_T structure. 


The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows: 


“The number of bytes of encrypted data that is stored in 
this validation list entry. If the QsyEncryptData attribute 
is 0 or the QRETSVRSEC system value is '0'", the length 


int Encr_Data_Len 
will always be 0. 


| unsigned int | Encr_Data_CCSID | The CCSID associated with the encrypted data. 


unsigned char | Encr_Data[600] “If the QsyEncryptData attribute is 1 and the 
QRETSVRSEC system value is '1', then the encrypted 
data that is stored in the entry will be decrypted and 
returned in this field. If the QsyEncryptData attribute is 


0 or the QRETSVRSEC system value is '0', then the 
encrypted data cannot be returned, and the contents of 
this field are unpredictable. 


The format of the Qsy_Entry_Data_Info_T structure is as follows: 


| int | Entry_Data_Len | The length of the entry data. 
| unsigned int | Entry_Data_CCSID | The CCSID associated with the entry data. 
| unsigned char | Entry_Data[1000] | The entry data. 


Return Value 


O QsyFindNextValidationLstEntry() was successful. The return value points to the entry. 


-1 QsyFindNextValidationLstEntry() was not successful. The errno global variable is set to indicate 
the error. 


Error Conditions 


If QsyFindNextValidationLstEntry() is not successful, errno indicates one of the following errors: 
3401 [EACCES] 


The current user does not have *USE authority to the validation list object, or does not have 
*EXECUTE authority to the validation list object library. 


3406 [EAGAIN] 
The validation list object is currently locked by another process. 
3484 [EDAMAGE] 


The validation list object is damaged. 


3021 [EINVAL] 


Parameter value is not valid. 


3025, [ENOENT] 


The validation list object was not found. 


3026 [ENOREC] 


There are no more entries in the validation list object. 


3474 [EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. 


Example 


The following example finds all the entries in the validation list object WEBUSRS. 


#include <qsyvldl.h> 
#include <errno.h> 


main () 


{ 


#define VLD_LST "WEBUSRS WEBLIB : 
Qsy_Rtn_Vld_Lst_Ent_T entry_1l; 
Qsy_Rtn_Vld_Lst_Ent_T entry_2; 
Qsy_Rtn_Vld_Lst_Ent_T *input_info, 
*output_info, 


*temp; 
Qsy_Entry_ID_Info_T *input_entry; 
short int ve 
int rtn_errno; 


/* Initialize pointers to input and output buffers. 

output_info = addr(entry_1); 

input_info = addr(entry_2); 

/* Get the first entry in the validation list. 

rtn_errno = QsyFindFirstValidationLstEntry ( 
(Qsy_Qual_Name_T *)&VLD_LST, 
output_info) ) 


while (0 == rtn_errno) 
{ /* Process all the entries in the validation list. 


(process the entry) 


/* Switch the pointers to the buffers so that the output from 


*/ 


Ay 


ai 


a 


/* the last find operation is used as input to the 'find-next' 


/* operation. 

temp = output_info; 
output_info = input_info; 
input_info = temp; 


/* Find the next entry. 

rtn_errno = QsyFindNextValidationLstEntry ( 
(Qsy_Qual_Name_T *) &VLD_LST, 
& (input_info->Entry_ID_Info), 
output_info) ) 


} 

/* Check if an error occurred. 

if (0 != rtn_errno && ENOREC != errno) 
perror("Find of validation list entry"); 


API introduced: V4R1 


Top | Security APIs | APIs by category 


ny, 


a7 


ay 


Find Validation List Entry (QSYFDVLE) API 


Required Parameter Group: 


Qualified validation list name Char(20) 
Entry ID information Char(*) 
Attribute information Char(*) 
Return entry Char(1724) 
Return attributes Char(*) 
Error Code Char(*) 


Service Program Name: QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The Find Validation List Entry (QSYFDVLE) API finds an entry in a validation list object and returns it. 
Also, any attributes associated with the entry can be returned. To find an entry, there must be an exact 
match in the entry for the value that is specified in the entry ID parameter and the length of the entry ID. 
For example, an entry ID value of SMITH with a length of 5 would not find an entry where the entry ID is 
SMITH and the length is 7. 


Authorities and Locks 


Validation List Object 
*USE 


Validation List Object Library 
*EXECUTE 


Note: If the QsyEncryptData attribute is set to 1, then the user must have *USE, *ADD, and *UPD 
authorities to the validation list to get the data to be encrypted returned in the encrypted data field. 


Required Parameter Group 
Qualified validation list name 
INPUT; CHAR(20) 


The qualified object name of the validation list in which to find the entry. The first 10 characters 
specify the validation list name, and the second 10 characters specify the library. 


You can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


Entry ID information 
INPUT; CHAR(*) 


The format of the entry ID information is as follows. See Field Descriptions for more information. 


| Offset 
| Dec | Hex |Type Field 


| 0 | 0 [BIN ARY(4) [Length of entry ID 
| 4 | 4 [BINARY(4) |CCSID of entry ID 
| 8 | 8 |CHAR(*) [Entry ID 


Attribute information 
INPUT; CHAR(*) 


The format of the attribute information is as follows. See Field Descriptions for more information. 


| Offset 
a c | Hex |Type Field 


| | [BIN ARY(4) [N umber of attributes 
| 4 | 4 |CHAR(*) [Attribute structures 


The format of the attribute structure is as follows. See Field Descriptions for more information. 


| Offset 
a c | Hex |Type Field 


Re Bel OO oe 
ee ee 
ae BIN Sanya [Displacement to attribute ID = 
[ 16 [ 10 |BINARY(4) [Length ofattributeID == 
[ 20 | 14 |BINARY(4) [Bytes provided forattribute = 
[| [| CHAR()—[AttributeID 


Return entry 
OUTPUT; CHAR(1724) 


The format of the return entry information is as follows. See Field Descriptions for more 
information. 


[| Dec | Hex |Type |Field 

[0 | 0 |BINARY@) |CengthofenyID—~—~S~CS 
[| 4 [ 4  |BINARY(@)  |CCSIDofenryID 
SC 
ie fnaRYG)— [eit ened 
| 720 [| 2D0 |BINARY(4) |CCSIDofdata 
[ 724 | 2D4 |CHARGO00) [Daa =~=~~SCS*~CS 
| 1724 | 6BC |CHAR(20) [Reserved 


Return attributes 
OUTPUT; CHAR(*) 


The format of the return attributes information is as follows. See Field Descriptions for more 
information. 


[Offset 
= c | Hex |Type Field 


The size of this buffer must be 24 bytes multiplied by the number of attributes, plus the bytes 
provided in the buffer for each attribute. For example, if you are requesting 2 attributes and 
providing 8 bytes for one attribute and 5 bytes for the other attribute, you would need a 61-byte 
buffer. If the buffer is not large enough, the results are unpredictable. 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Field Descriptions 


Attribute ID. The ID of the attribute. For system-defined attributes, the allowed values are: 
String value Description 


QsyEncryptData This is the attribute that is associated with the data to encrypt. 


QsyEntryUsage This is the entry usage information attribute. 


QsyX509Cert This is the X.509 certificate attribute for the entry. 


Attribute location. Where the attribute is stored. The allowed value is: 


0 The attribute is stored in the validation list object. 


Attribute structures. Zero or more attribute structures that define the attributes that are associated with the 
entry. 


Attribute type. The type of attribute. The allowed value follows: 


0 This is a system-defined attribute. 


Attribute value. The value of the returned attribute. If the attribute ID is QsyEncryptData or QsyX509Cert, 
the data will be in the form of variable length character array. If the attribute ID is QsyEntryUsage, the data 
will be in the form of Qsy_Rtn_Entry_Usage_Attr_T. 


The format of the Qsy_Rtn_Entry_Usage_Attr_T structure is as follows. See Field Descriptions for more 
information. 


| Offset 
ae Hex |Type Field 


Bytes available. The number of bytes of data that is available to be returned to the user for the current 
attribute. If all data is returned, bytes available is the same as the number of bytes returned. If the bytes 
available is 16, then the specified attribute is not defined for this entry. 


Bytes provided for attribute. The number of bytes provided in the return attributes buffer for the attribute 
value. The minimum length is 0. If 0 is specified, the bytes available will indicate if the attribute exists and 
how many bytes of data are needed to return the attribute. 


Bytes returned. The number of bytes of data that is returned to the user for the current attribute. This is the 
lesser of the number of bytes available to be returned and bytes provided for attribute plus 20. 


CCSID of attribute. An integer that represents the CCSID for the attribute. Valid CCSID values are in the 
range 0 through 65535. This value is the CCSID value that was specified when the attribute was added or 
changed. If the value is 0, then no CCSID value was stored with the attribute. 

CCSID of encrypted data. An integer that represents the CCSID for the encrypted data. 

CCSID of data. An integer that represents the CCSID for the data. 


CCSID of entry ID. An integer that represents the CCSID for the entry ID. Valid CCSID values are in the 
range 0 through 65535. This field is not used to find the entry. The value is returned in the return entry. 


Create date. The date the entry was added to the validation list, in *DTS (date-time stamp) format. 


Data. The data that is stored in the validation list entry. 
Displacement to attribute ID. The displacement in the attribute entry to the start of the attribute ID. 


“Encrypted data. If the QsyEncryptData attribute for this entry is 1 and the QRETSVRSEC system value 
is 'l', then the encrypted data that is stored in the entry will be decrypted and returned in this field. If the 
QsyEncryptData attribute is 0 or the QRETSVRSEC system value is '0', then the encrypted data cannot be 
returned and the contents of this field are unpredictable.*& 


Encrypted data change date. The date the encrypted data was last changed, in *DTS (date-time stamp) 
format. 


Entry ID. The data that is used to find the entry in the validation list. 
Last used date. The date of the last successful verify, in *DTS (date-time stamp) format. 


Length of attribute. The length (in bytes) of the returned attribute value. This value will be less than or 
equal to the bytes provided for attribute. 


Length of attribute entry. The length (in bytes) of the current entry. This length can be used to access the 
next entry, and must be a multiple of 4. 


Length of attribute ID. The number of bytes of data in the attribute ID. The length must be greater than 0. 


Length of data. The number of bytes of data that is stored in this validation list entry. Possible values are 0 
to 1000. 


2Length of encrypted data. The number of bytes of encrypted data that is stored in this validation list 
entry. Possible values are 0 to 600. If the QsyEncryptData attribute is 0 or the QRETSVRSEC system value 
is '0', then the length will always be 0.% 


Length of entry ID. The number of bytes of data that is provided as the entry ID. Possible values are 1 
through 100. 


Not valid verify count. The number of times that incorrect encrypted data has been specified on a verify 
since the last successful verify. 


Number of attributes. The number of attributes to be returned. This value must be greater than or equal to 
0. If the value is 0, then no attributes will be returned. 


Reserved. This is an ignored field. 


Error Messages 


Message ID Error Message Text 

CPFAOAA E Error occurred while attempting to obtain space. 

CPF226B E Validation list entry does not exist. 

CPF3CF1 E Error code parameter not valid. 

CPF3C36 E Number of parameters, &1, entered for this API was not valid. 


CPF3C90 E Literal value cannot be changed. 


CPF9801 E 
CPF9802 E 
CPF9803 E 
CPF9804 E 
CPF9872 E 


Object &2 in library &3 not found. 
Not authorized to object &2 in &3. 
Cannot allocate object &2 in library &3. 
Object &2 in library &3 damaged. 


Program or service program &1 in library &2 ended. Reason code &3. 


API introduced: V4R2 


Top | Security APIs | APIs by category 


QsyFindValidationLstEntry()--Find Validation 
List Entry API 


Syntax 


#include <qsyvldl.h> 


int QsyFindValidationLstEntry 
(Qsy_Qual_Name_T *Validation_Lst, 
Qsy_Entry_ID_Info_T *Entry_ID, 
Qsy_Rtn_Vld_Lst_Ent_T *Rtn_Entry); 


Service Program Name: QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsyFind ValidationLstEntry() function finds an entry in a validation list object. The function then 
returns the information for the entry in the buffer that is pointed to by the Rin_Entry parameter. To find an 
entry, there must be an exact match in the entry for the value that is specified in the Entry_ID parameter 
and the length of the entry ID. For example, an entry ID value of "SMITH" with a length of 5 would not 
find an entry where the entry ID is "SMITH " and the length is 7. 


Authorities 


Validation List Object 
*USE 


Validation List Object Library 
*EXECUTE 
Note: If the QsyEncryptData attribute is set to QSY_VFY_FIND_E (1), then the user must have *USE, 


*ADD, and *UPD authority to the validation list to get the data to be encrypted returned in the Rtn_Entry 
parameter. 


Parameters 


Validation_Lst 
(Input) 
A pointer to the qualified object name of the validation list in which to find the entry. The first 10 


characters specify the validation list name, and the second 10 characters specify the library. You 
can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 
Entry_ID 


(Input) 


A pointer to the entry ID information. The format of the Qsy_Entry_ID_Info_T structure is as 
follows: 


int Entry_ID_Len The number of bytes of data that is provided as the entry 
ID. Possible values are from 1 through 100. 

unsigned int Entry_ID_CCSID | An integer that represents the CCSID for the entry ID. 
Valid CCSID values are in the range 0 through 65535. 
This value is not used to find the entry. 


| unsigned char | Entry_ID[100] 


Rtn_Entry 
(Output) 


The data that is used to identify this entry in the validation 
list. 


A pointer to the buffer where the entry information is placed. The buffer must be allocated to the 
size of the Qsy_Rtn_Vld_Lst_Ent_T structure or the results will be unpredictable. The format of the 
Qsy_Rtn_Vld_Lst_Ent_T structure is as follows: 


Qsy_Entry_ID_Info_T | Entry_ID_Info | The entry ID information structure. 


Qsy_Entry_Encr_Data_Info_T |} Encr_Data_Info The data to be encrypted information 
structure. 


Qsy_Entry_Data_Info_T | Entry_Data_Info | The | The entry data information structure. | The entry data information structure. information structure. 
| char | Reserved[4] | This is an ignored field, is an | This is an ignored field, field. 


void * Entry_More_Info | A pointer to additional information. This 
pointer is currently set to NULL. 


See the Entry_ID parameter for the format of the Qsy_Entry_ID_Info_T structure. 


The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows: 


int Encr_Data_Len “The number of bytes of encrypted data that is stored in 
this validation list entry. If the QsyEncryptData attribute 
is 0 or the QRETSVRSEC system value is '0', the length 
will always be 0.% 


| unsigned int | Encr_Data_CCSID | The CCSID associated with the encrypted data. 


unsigned char |} Encr_Data[600] >If the QsyEncryptData attribute is 1 and the 
QRETSVRSEC system value is '1', then the encrypted 
data that is stored in the entry will be decrypted and 
returned in this field. If the QsyEncryptData attribute is 


0 or the QRETSVRSEC system value is '0', then the 
encrypted data cannot be returned, and the contents of 
this field are unpredictable. 


The format of the Qsy_Entry_Data_Info_T structure is as follows: 


| int | Entry_Data_Len | The length of the entry data. 
| unsigned int | Entry_Data_CCSID | The CCSID associated with the entry data. 
| unsigned char | Entry_Data[1000] | The entry data. 


Return Value 


0 QsyFindValidationLstEntry() was successful. The return value points to the entry. 


-1 QsyFindValidationLstEntry() was not successful. The errno global variable is set to indicate the 
error. 


Error Conditions 


If QsyFindValidationLstEntry() is not successful, errno indicates one of the following errors: 
3401 [EACCES] 


The current user does not have *USE authority to the validation list object, or does not have 
*EXECUTE authority to the validation list object library. 


3406 [EAGAIN] 
The validation list object is currently locked by another process. 
3454 [EDAMAGE] 


The validation list object is damaged. 
3021 [EINVAL] 

Parameter value is not valid. 
3025, [ENOENT] 


The validation list object was not found. 


3026 [ENOREC] 
Specified entry does not exist. 
3474 [EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. 


Example 


The following example finds all the entries in the validation list object WEBUSRS where the entry ID starts 
with ‘abc’. 


#include <qsyvldl.h> 
#include <errno.h> 


main () 
{ 
#define VLD_LST "WEBUSRS WEBLIB " 
Qsy_Rtn_Vld_Lst_Ent_T entry_1l; 
Qsy_Rtn_Vld_Lst_Ent_T entry_2; 
Qsy_Rtn_Vld_Lst_Ent_T *input_info, 
*output_info, 


*temp; 
Qsy_Entry_ID_Info_T *input_entry; 
short int i? 
int rtn_errno; 
/* Set up entry ID to find. */ 


strncpy (entry_1.Entry_ID_Info.Entry_ID,"abc",3); 
entry_1.Entry_ID_Info.Entry_ID_Len = 3; 


/* Initialize pointers to input and output buffers. */ 
input_info = addr(entry_1); 
output_info = addr(entry_2); 


/* Try to find an entry for ‘abc'. */ 
rtn_errno = QsyFindValidationLstEntry ( 
(Qsy_Qual_Name_T *)&VLD_LST, 
é&entry_1.Entry_ID_Info, 
output_info) ) 


/* If an 'abc' entry does not exist. */ 
if (O != rtn_errno && ENOREC == errno) 
/* Find the next entry after ‘abc’. */ 


rtn_errno = QsyFindNextValidationLstEntry ( 
(Qsy_Qual_Name_T *)&VLD_LST, 
é&entry_1.Entry_ID_Info, 
output_info) ) 


while (0 == rtn_errno && 
3 <= output_info->Entry_ID_Info.Entry_ID_Len && 
0 == strncmp (output_info->Entry_ID_Info.Entry_ID, "abc", 3) ) 


{ /* Process all the entries in the validation list that */ 


/* begin with 'abc'. 


(process the entry) 


/* Switch the pointers to the buffers so that the output from 
/* the last find operation is used as input to the 'find-next' 
/* operation. 

temp = output_info; 

output_info = input_info; 

input_info = temp; 


/* Find the next entry. 

rtn_errno = QsyFindNextValidationLstEntry ( 
(Qsy_Qual_Name_T *)&VLD_LST, 
& (input_info->Entry_ID_Info), 
output_info) ) 


} 

/* Check if an error occurred. 

if (0 != rtn_errno && ENOREC != errno) 
perror("Find of validation list entry"); 
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QsyFindValidationLstEntryAttrs()--Find 
Validation List Entry Attributes API 


Syntax 


#include <qsyvldl.h> 


int QsyFindValidationLstEntryAttrs 
(Qsy_Qual_Name_T *Validation_Lst, 
Qsy_Entry_ID_Info_T *Entry_ID, 
Qsy_Rtn_Vld_Lst_Ent_T *Rtn_Entry, 
Qsy_Attr_Info_T *Rtn_Attributes); 


Service Program Name: QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsyFind ValidationLstEntryAttrs() function finds an entry in a validation list object, and the 
attributes associated with the entry. The function then returns the information for the entry in the buffer that 
is pointed to by the Rin_Entry parameter, and the information for the attributes in the buffer that is pointed 
to by the Rin_Attributes parameter. To find an entry, there must be an exact match in the entry for the value 
that is specified in the Entry_ID parameter and the length of the entry ID. For example, an entry ID value of 
"SMITH" with a length of 5 would not find an entry where the entry ID is "SMITH " and the length is 7. 


Authorities 


Validation List Object 
*USE 


Validation List Object Library 
*EXECUTE 


Note: If the QsyEncryptData attribute is set to QSY_VWFY_FIND (1), then the user must have *USE, 
*ADD, and *UPD authority to the validation list to get the data to be encrypted returned in the Rtn_Entry 
parameter. 


Parameters 
Validation_Lst 
(Input) 


A pointer to the qualified object name of the validation list in which to find the entry. The first 10 
characters specify the validation list name, and the second 10 characters specify the library. You 


can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


Entry_ID 
(Input) 


A pointer to the entry ID information. The format of the Qsy_Entry_ID_Info_T structure is as 
follows: 


int Entry_ID_Len The number of bytes of data that is provided as the entry 
ID. Possible values are from 1 through 100. 

unsigned int Entry_ID_CCSID | An integer that represents the CCSID for the entry ID. 
Valid CCSID values are in the range 1 through 65535. 
This value is not used to find the entry. 


| unsigned char | Entry_ID[] 


Rtn_Entry 
(Output) 


The data that is used to identify this entry in the validation 
list. 


A pointer to the buffer where the entry information is placed. The buffer must be allocated to the 
size of the Qsy_Rtn_Vld_Lst_Ent_T structure or the results will be unpredictable. The format of the 
Qsy_Rtn_Vld_Lst_Ent_T structure is as follows: 


Qsy_Entry_ID_Info_T Entry_ID_Info The | The entry ID information structure. ID | The entry ID information structure. structure. 


Qsy_Entry_Encr_Data_Info_T |} Encr_Data_Info The data to be encrypted information 
structure. 


Qsy_Entry_Data_Info_T Entry_Data_Info | The entry data information structure 
| char Reserved[4] | This is an ignored field. 


void * Entry_More_Info | A pointer to additional information. This 
pointer is currently set to NULL. 


See the Entry_ID parameter for the format of the Qsy_Entry_ID_Info_T structure. 


The format of the Qsy_Entry_Encr_Data_Info_T structure is as follows: 


“The number of bytes of encrypted data that is stored in 
this validation list entry. If the QsyEncryptData attribute 
is 0 or the QRETSVRSEC system value is '0'", the length 


int Encr_Data_Len 
will always be 0. 


| unsigned int | Encr_Data_CCSID | The CCSID associated with the encrypted data. 


unsigned char | Encr_Data[600] “If the QsyEncryptData attribute is 1 and the 
QRETSVRSEC system value is '1', then the encrypted 
data that is stored in the entry will be decrypted and 
returned in this field. If the QsyEncryptData attribute is 


0 or the QRETSVRSEC system value is '0', then the 
encrypted data cannot be returned, and the contents of 
this field are unpredictable. 


The format of the Qsy_Entry_Data_Info_T structure is as follows: 


| int | Entry_Data_Len | The length of the entry data. 
| unsigned int | Entry_Data_CCSID | The CCSID associated with the entry data. 
| unsigned char | Entry_Data[1000] | The entry data. 


Rtn_Attributes 


(Input) A pointer to a structure that indicates the attributes to return. The format of the 
Qsy_Attr_Info_T structure is as follows: 


Number_Attrs | The number of attributes to be returned. This value 
must be greater than 0. 


7 char | Res_Align[12] | Reserved for boundary alignment, for | Reserved for boundary alignment, alignment. 
| Qsy_Attr_Descr_T | Attr_Descr[] | An array of attribute description structures. 


The format of the Qsy_Attr_Descr_T structure is as follows: 


int Attr_Location 
int Attr_Type 


Where the attribute is stored. The allowed value follows: 


O QSY_IN_VLDL The attribute is stored in the validation list 
object. 


The type of attribute. The allowed value follows: 


0 OSY_SYSTEM_ATTR This is a system-defined attribute. 


union | Attr_Res Reserved data. This value must be hexadecimal zero. 
Res_1[8] 
char * | Attr_ID The ID of the attribute. For system-defined attributes, the allowed 
values are: 
| | String value | Description 
| | QsyEncryptData | This is the attribute that is associated with the data to encrypt. 
| | QsyX509Cert | This is the X.509 certificate attribute for the entry. 
| | QsyEntry Usage | This is the entry usage information attribute. 
union | Attr_Other_Descr | Reserved data. This value must be hexadecimal zero. 
Res_1[32] 
| union | Attr_Data_Info | The information that describes the attribute data. 
union | Attr_Other_Data Reserved data. This value must be hexadecimal zero. 
Res_1[32] 


The format of the Attr_Data_Info union is as follows: 


Qsy_In_VLDL_T |} Attr_VLDL The attribute data information for an attribute that is 


stored in the validation list object. 
union Attr_In_Other | Reserved data. The last 64 bytes must be hexadecimal 
Res_1[96] zero. 


The format of the Qsy_In_VLDL_T structure is as follows: 


int Attr_CCSID | An integer that represents the CCSID for the attribute. Valid CCSID 
values are in the range -1 through 65535. This value is not used. 

int Attr_Len The number of bytes of data in the buffer to return the attribute value. 
The minimum length is 12. 

union | Attr_Res Reserved data. This value must be hexadecimal zero. 

Res_1[8] 
| void * | Attr_Value | A pointer to a Qsy_Rtn_VLDL_Attr_T structure in which to return the 

attribute. 


The format of the Qsy_Rtn_VLDL_Attr_T structure is as follows: 


; Bytes_Returned 


Bytes_Available 


The number of bytes of data that is returned to the user in 
the attribute buffer. This is the lesser of the number of 
bytes available to be returned and Attr_Len in 
Qsy_In_VLDL_T. 


The number of bytes of data that is available to be returned 
to the user in the attribute buffer. If all data is returned, 
bytes available is the same as the number of bytes returned. 
If the bytes available is 12, then the specified attribute is 
not defined for this entry. 


value is the CCSID value that was specified when the 


| int | Attr_Len The length (in bytes) of the returned attribute. 
unsigned int Attr_CCSID An integer that represents the CCSID for the attribute. 
attribute was added or changed. If the value is 0, then no 
CCSID value was stored with the attribute. 


Valid CCSID values are in the range 0 through 65535. This 
| unsigned char | Attr_Data[] The value of the returned attribute. 


The format of the Qsy_Rtn_Entry_Usage_Attr_T structure is as follows: 


| char | Create_Date[8] | The date the entry was added to the validation list. 
| char | Last_Used_Date[8] | The date of the last successful verify. 
| char | Encr_Data_Chg_Date[8] | The date the encrypted data was last changed. 


int Not_Valid_Verify_Count | The number of times that incorrect encrypted data has been 
specified on a verify since the last successful verify. 


Return Value 


QsyFind ValidationLstEntryAttrs() was successful. The return value points to the entry. The 
return attribute points to the attribute list. 


QsyFind ValidationLstEntryAttrs() was not successful. The errno global variable is set to indicate 
the error. 


Error Conditions 


If QsyFindValidationLstEntryA ttrs() is not successful, errno indicates one of the following errors: 
3401 [EACCES] 


The current user does not have *USE authority to the validation list object, or does not have 
*EXECUTE authority to the validation list object library. 


3406 [EAGAIN] 

The validation list object is currently locked by another process. 
3484 [EDAMAGE] 

The validation list object is damaged. 
3021 [EINVAL] 

Parameter value is not valid. 
3025, [ENOENT] 

The validation list object was not found. 
3026 [ENOREC] 

Specified entry does not exist. 
3404 [ENOSPC] 

No space available. 
3474 [EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. 


Example 


The following example finds an entry for a user named FRED in the validation list object WEBUSRS, and 
returns the attribute that is associated with the encrypted data field. 


#include <stdlib.h> 
#include <qsyvldl.h> 
#include <errno.h> 


main () 

{ 
#define VLD_LST "WEBUSRS WEBLIB : 
Qsy_Rtn_Vld_Lst_Ent_T rtn_ent; 


struct { 
Qsy_Attr_Info_T attr_info; 
Qsy_Attr_Desc_T attr_desc; 


} rtn_attr; 


struct { 
Qsy_Rtn_VLDL_Attr_T encr_info; 


char encr_val; 
} encr_attr; 
Qsy_Entry_ID_Info_T *input_entry; 
/* Set up entry ID to find. ay: 


strncpy(rtn_ent.Entry_ID_Info.Entry_ID, "FRED", 4); 
rtn_ent.Entry_ID_Info.Entry_ID_Len = 4; 


/* Set up the attribute information. a) 
/* Initialize reserved fields. * / 
memset (rtn_attr.attr_desc.Attr_Res.Res_l, 
0, 


sizeof (rtn_attr.attr_desc.Attr_Res.Res_1)); 

memset (rtn_attr.attr_desc.Attr_Other_Descr.Res_l1, 

0, 

sizeof (rtn_attr.attr_desc.Attr_Other_Descr.Res_1)); 

memset (rtn_attr.attr_desc.Attr_Data_Info.Attr_In_Other.Res_1, 

0, 

sizeof (rtn_attr.attr_desc.Attr_Data_Info.Attr_In_Other.Res_1)); 
memset (rtn_attr.attr_desc.Attr_Other_Data.Res_1, 

0, 

sizeof (rtn_attr.attr_desc.Attr_Other_Data.Res_1)); 


/* Set number of attrs. xf 
rtn_attr.attr_info.Numbers_Attrs = 1; 

/* Set location of attribute. */ 
rtn_attr.attr_desc.Attr_Location = QSY_IN_VLDL; 

/* Set attribute type. */ 
rtn_attr.attr_desc.Attr_Type = QSY_SYSTEM_ATTR; 

/* Set attribute type. */ 
rtn_attr.attr_desc.Attr_ID = (char *)QSY_ENCRYPT_DATA; 

/* Set length to retrieve. xf 


rtn_attr.attr_desc.Attr_Data_Info.Attr_VLDL.Attr_Len = 
sizeof(encr_attr); 


/* Set CCSID value. */ 
rtn_attr.attr_desc.Attr_Data_Info.Attr_VLDL.Attr_CCSID = -1; 
/* Set pointer to return buffer * / 


rtn_attr.attr_desc.Attr_Data_Info.Attr_VLDL.Attr_Value = 
(void *)&encr_attr; 


/* Try to find an entry for 'FRED'. a 
if (0 == QsyFindValidationLstEntryAttrs ( 
(Qsy_Qual_Name_T *) &VLD_LST, 
&rtn_ent.Entry_ID_Info, 
&rtn_ent, 
(Qsy_Attr_Info_T *) &rtn_attr) ) 
{ /* Entry was found a 


(process the entry) 


else /* Error on find of entry. 
perror("Find of validation list entry"); 


API introduced: V4R2 
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Open List of Validation List Entries 
(QSYOLVLE) API 


Required Parameter Group: 


Receiver variable Char(*) 
Length of receiver variable Binary(4) 
List information Char(80) 
Number of records to return Binary(4) 
Format name Char(8) 
Qualified validation list name Char(20) 
Error code Char(*) 


Default Public Authority: *USE 


Threadsafe: No 


The Open List of Validation List Entries (QS YOLVLE) API returns a list of validation list entries in a 
validation list object. Upon successful completion of this API, a handle is returned in the list information 
parameter. You may use this handle on subsequent calls to the following APIs: 


e Get List Entries (QGYGTLE) 
e Find List Entry (QGYFNDE) 
e@ Close List (QGYCLST) 


Authorities and Locks 


Authority to Validation List 
*USE 

Authority to Validation List Library 
*EXECUTE 


Required Parameter Group 


Receiver variable 
OUTPUT; CHAR(*) 
The receiver variable that receives the information requested. You can specify the size of the area 


to be smaller than the format requested as long as you specify the length parameter correctly. As a 
result, the API returns only the data that the area can hold. 


Length of receiver variable 
INPUT; BINARY(4) 


The length of the receiver variable. If the length is larger than the size of the receiver variable, the 
results are not predictable. 


List Information 
OUTPUT; CHAR(80) 


Information about the list that is created by this program. See Format of List information for a 
description of the layout of this parameter. 


Number of records to return 
INPUT; BINARY(4) 


The number of records in the list to put into the receiver variable. Possible values follow: 
-1 The entire list is built synchronously. 
0 The entire list is built asynchronously in a server job. 


Positive number of records At least that many records will be built synchronously and the 
remainder will be built asynchronously in a server job. 


Format name 
INPUT; CHAR(8) 


The name of the format that is used to return information about the validation list entries. 
You can specify these formats: 


VLDEOlOO The order and format of the data that is returned in the receiver variable for each 
validation list entry in the list. 


Qualified validation list name 
INPUT; CHAR(20) 
The qualified object name of the validation list that contains the entries to return. The first 10 


characters specify the validation list name, and the second 10 characters specify the library. You 
can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 
Error code 
1/0; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Format of List information 


For detailed descriptions of the fields in the tables, see Field Descriptions. 


| Offset 
| Dec Hex |Type Field 


| 0 0 BINARY(4) Total records 

| 4 4 BINARY(4) Records returned 

| 8 8 CHAR(4) [Request handle 

| 12 C BINARY(4) [Rec ord length 

| 16 10. |CHAR(1) Information complete indicator 
| 17 11 |CHAR(3) Date and time created 

| 30 1E |CHAR(1) [List status indicator 

| 31 1F |CHAR(1) Reserved 

| 32 20 |BINARY(4) Length of information returned 
| 36 24 |BINARY(4) [First record in buffer 

| 40 28 |CHAR(40) Reserved 


Field Descriptions 


Date and time created. The date and time when the list was created. The 13 characters are: 
I Century, where 0 indicates years 19xx and 1 indicates years 20xx. 
2-7 The date, in YYMMDD (year, month, and day) format. 


S-13 The time of day, in HHMMSS (hours, minutes, and seconds) format. 


First record in buffer. The number of the first record in the receiver variable. 
Information complete indicator. Whether all information that was requested has been supplied. 


I Incomplete information. An interruption causes the list to contain incomplete information about a 
buffer or buffers. 


P Partial and accurate information. Partial information is returned when the maximum space was used 
and not all of the buffers requested were read. 


C Complete and accurate information. All the buffers requested are read and returned. 


Length of information returned. The size in bytes of the information returned in the receiver variable. 
List status indicator. The status of building the list. Possible values follow: 
0 The list building is pending. 


I The list is in the process of being built. 


2 The list has been completely built. 


3 Anerror occurred when building the list. An error will be signalled to the caller of the QGYGTLE 
API. 


4 The list is primed and ready to be built. 


Record length. The length of each record of information returned. This value will be set to 0 because the 
record lengths are variable. You can obtain the length of individual records from the records themselves. 


Records returned. The number of records returned in the receiver variable. 


This is the smallest of the following three values: 
e@ The number of records that fit into the receiver variable. 
e The number of records in the list. 


e The number of records that are requested. 


Request handle. The handle of the request that can be used for subsequent requests of information from the 
list. The handle is valid until the Close List (QGYCLST) API is called to close the list, or until the job ends. 


Note: This field should be treated as a hexadecimal field. It should not be converted from one CCSID to 
another, for example, EBCDIC to ASCII, because doing so could result in an unusable value. 


Reserved. An ignored field. 


Total records. The total number of records available in the list. 


VLDE0100 Format 


The following table describes the order and format of the data that is returned in the receiver variable for 
each validation list entry in the list. For detailed descriptions of the fields in the table, see Field 


Descriptions. 


| Offset 
| D Hex |Type Field 


[0 [0 —[BINARY@®) — [Length ofemey 
| 4 | 4. |BINARY()  [DisplacementtoentryID = = = 
[| 8 | 8 J|BINARY(4)  [LengthofenryID 2 
| 12 [ C  |BINARY()  |CCSIDofenryID 
[ 16 | 10 |BINARY(G) [Displacement to encrypted data ——~—~S~S 
| 20 | 14 |BINARY(4) [Length ofencrypteddata = 
[24 [18 |BINARY(@  |CCSID of encrypteddata—~—~=~S*S 
| 28 | 1C |BINARY(4)  [Displacementtoentrydata == 
| 32 | 20 |BINARY(4)  |Lengthofentrydata = = = 
| 36 [| 24 |BINARY(4) |CCSIDofentrydaa == = 
ff CHAR@) Entry ID 
| CHAR(*) Encrypted data 

[| [CHARGH) [Entrydata 


Field Descriptions 


CCSID of encrypted data. The CCSID of the encrypted data that was specified when the validation list 
entry was added or changed. 


CCSID of entry data. The CCSID of the entry data that was specified when the validation list entry was 
added or changed. 


CCSID of entry ID. The CCSID of the entry ID that was specified when the validation list entry was 
added. 


Displacement to encrypted data. The displacement in the entry to the start of the encrypted data. 
Displacement to entry data. The displacement in the entry to the start of the entry data. 

Displacement to entry ID. The displacement in the entry to the start of the entry ID. 

“Encrypted data. The encrypted data associated with the validation list entry. This data is only returned if 


the entry specifies that the encrypted data is two way encrypted, the QRETSVRSEC system value is '1', and 
the user has *USE, *ADD, and *UPD authority to the validation list. If the data is to be returned, it is 


decrypted and returned in this field.“& 
Entry data. The data associated with the validation list entry. 
Entry ID. The entry ID for the validation list entry. 


Length of encrypted data. The length (in bytes) of the encrypted data. If the data is one-way encrypted, 
the QRETSVRSEC system value is '0’", or the user is not authorized to have the encrypted data returned, this 


value will be 0.4% 
Length of entry. The length (in bytes) of the current entry. This length can be used to access the next entry. 
Length of entry data. The length (in bytes) of the entry data. 


Length of entry ID. The length (in bytes) of the entry ID. 


Error Messages 


Message ID Error Message Text 

CPF24B4 E Severe error while addressing parameter list. 
CPF226B E Validation list entry does not exist. 

CPF3C19 E Error occurred with receiver variable specified. 
CPF3C21 E Format name &1 is not valid. 

CPF3C90 E Literal value cannot be changed. 

CPF3CF1 E Error code parameter not valid. 

CPF9801 E Object &2 in library &3 not found. 

CPF9802 E Not authorized to object &2 in &3. 


CPF9803 E Cannot allocate object &2 in library &3. 

CPF9804 E Object &2 in library &3 damaged. 

CPF9821 E Not authorized to program &1 in library &2. 

CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
GUI0002 E &2 is not valid for length of receiver variable. 


GUI0027 E &1 is not valid for number of records to return. 
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QsyRemovevValidationLstEntry()--Remove 
Validation List Entry API 


Syntax 


#include <qsyvldl.h> 


int QsyRemoveValidationLstEntry 
(Qsy_Qual_Name_T *Validation_Lst, 
Qsy_Entry_ID_Info_T *Entry_ID); 


Service Program Name: QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsyRemove ValidationLstEntry() function removes an entry from a validation list object. To identify 
an entry to be removed, there must be an exact match in the entry for the value that is specified in the 
Entry_ID parameter and the length of the entry ID. For example, an entry ID value of "SMITH" with a 
length of 5 would not remove an entry where the entry ID is "SMITH " and the length is 7. 


Authorities 


Validation List Object 
*USE and *DLT 
Validation List Object Library 
*EXECUTE 


Parameters 


dt> Validation_Lst 
(Input) 


A pointer to the qualified object name of the validation list that contains the entry to remove. The 
first 10 characters specify the validation list name, and the second 10 characters specify the library. 
You can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


Entry_ID 
(Input) 


A pointer to the entry ID information. Qsy_Entry_ID_Info_T structure is as follows: 


int Entry_ID_Len The number of bytes of data that is provided as the entry 
ID. Possible values are from 1 through 100. 

unsigned int Entry_ID_CCSID | An integer that represents the CCSID for the entry ID. 
Valid CCSID values are in the range 0 through 65535. 
This value is not used to remove the entry. 


unsigned char | Entry_ID[100] The data that is used to identify this entry in the validation 
| | | list. 


Return Value 


O QsyRemoveValidationLstEntry() was successful. 
-1 QsyRemoveValidationLstEntry() was not successful. 


The errno global variable is set to indicate the error. 


Error Conditions 


If QsyRemoveValidationLstEntry() is not successful, errno indicates one of the following errors: 
3401 [EACCES] 


The current user does not have *USE and *DLT authorities to the validation list object, or does 
not have *EXECUTE authority to the validation list object library. 


3406 [EAGAIN] 
The validation list object is currently locked by another process. 
3484 [EDAMAGE] 
The validation list object is damaged. 
3021 [EINVAL] 
Parameter value is not valid. 
3025, [ENOENT] 
The validation list object was not found. 
3026 [ENOREC] 


Specified entry does not exist. 


3474 [EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. 


Example 


The following example removes an entry for a user named FRED in the validation list object WEBUSRS. 


See Code disclaimer information for information pertaining to code examples. 


#include <qsyvldl.h> 


main () 


{ 
#define VLD_LST "WEBUSRS WEBLIB z 


Qsy_Entry_ID_Info_T entry_info; 


entry_info.Entry_ID_Len = 4; 
strncpy (entry_info.Entry_ID, "FRED",entry_info.Entry_ID_Len); 


if (0 != QsyRemoveValidationLstEntry ( 
(Qsy_Qual_Name_T *) &VLD_LST, 
é&entry_info) ) 
perror ("QsyRemoveValidationLstEntry()"); 


API introduced: V4R1 


Top | Security APIs | APIs by category 


Remove Validation List Entry (QSYRMVLE) API 


Required Parameter Group: 


1 = Qualified validation list name Input Char(20) 
2 Entry ID information Input Char(**) 


3 Error code VO Char(*) 


Threadsafe: Yes 


The Remove Validation List Entry (QSYRMVLE) API removes an entry from a validation list object. To 
identify an entry to be removed, there must be an exact match in the entry for the value that is specified in 
the entry ID parameter and the length of the entry ID. For example, an entry ID value of "SMITH" with a 
length of 5 would not remove an entry where the entry ID is "SMITH " and the length is 7. 


Authorities and Locks 


Validation List Object 
*USE and *DLT 
Validation List Object Library 
*EXECUTE 


Required Parameter Group 
Qualified validation list name 
INPUT; CHAR(20) 


The qualified object name of the validation list that contains the entry to remove. The first 10 
characters specify the validation list name, and the second 10 characters specify the library. You 
can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


Entry ID information 
INPUT; CHAR(*) 


The format of the entry ID information is as follows. See the Field Descriptions for more 
information. 


| Offset 
| Dec Hex /|Type Field 


| 0 0 BINARY(4) Length of entry ID 
| 4 4 BINARY(4) CCSID of entry ID 
| 8 8 CHAR(*) Entry ID 


Error code 
1/O; CHAR(*) 


The structure in which to return error information. For the format of the structure, see Error Code 
Parameter. 


Field Descriptions 


CCSID of entry ID. An integer that represents the CCSID for the entry ID. Valid CCSID values are in the 
range 0 through 65535. This field is not used to remove the entry. 


Entry ID. The data that is used to identify the entry to be removed from the validation list. 


Length of entry ID. The number of bytes of data that is provided as the entry ID. Possible values are 1 
through 100. 


Error Messages 


Message ID Error Message Text 

CPF226B E Validation list entry does not exist. 

CPF3CF1 E Error code parameter not valid. 

CPF3C36 E Number of parameters, &1, entered for this API was not valid. 
CPF3C90 E Literal value cannot be changed. 

CPF9801 E Object &2 in library &3 not found. 

CPF9802 E Not authorized to object &2 in &3. 

CPF9803 E Cannot allocate object &2 in library &3. 

CPF9804 E Object &2 in library &3 damaged. 


CPF9872 E Program or service program &1 in library &2 ended. Reason code &3. 
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QsyVerifyValidationLstEntry()--Verify 
Validation List Entry API 


Syntax 


#include <qsyvldl.h> 


int QsyVerifyValidationLstEntry 
(Qsy_Qual_Name_T *Validation_Lst, 
Qsy_Entry_ID_Info_T *Entry_ID, 
Qsy_Entry_Encr_Data_Info_T *Encrypt_Data)j; 


Service Program Name: Name QSYVLDL 


Default Public Authority: *USE 


Threadsafe: Yes 


The QsyVerify ValidationLstEntry() function verifies an entry in a validation list object. It verifies the 
entry by finding the validation list object, then finding the entry that is specified in the Entry_ID parameter. 
To find an entry, there must be an exact match in the entry for the value that is specified in the Entry_ID 
parameter and the length of the entry ID. For example, an entry ID value of "SMITH" with a length of 5 
would not find an entry where the entry ID is "SMITH " and the length is 7. 


If the entry is found, the data specified in the Encrypt_Data parameter is encrypted by the system and 
compared to the encrypted data that is stored for the entry. If the encrypted data fields do not match, then -2 
is returned by the function. 


The verification of an entry should be done within the same process as the work that is being done on 
behalf of this entry ID so that there is accountability for the actions that are taken. Also, an entry ID should 
be verified just before the work is done on behalf of that entry ID, instead of verifying a set of entry IDs 
and then doing work on behalf of the different entry IDs. 


Authorities 


Validation List Object 
*USE 

Validation List Object Library 
*EXECUTE 


Parameters 


Validation_Lst 


(Input) A pointer to the qualified object name of the validation list that contains the entry to verify. 
The first 10 characters specify the validation list name, and the second 10 characters specify the 
library. You can use these special values for the library name: 


*CURLIB The current library is used to locate the validation list. If there is no current library, 
QGPL (general purpose library) is used. 


*LIBL The library list is used to locate the validation list. 


Entry_ID 
(Input) 


A pointer to the entry ID information. The format of the Qsy_Entry_ID_Info_T structure is as 
follows: 


int Entry_ID_Len The number of bytes of data that is provided as the entry 
ID. Possible values are from 1 through 100. 

unsigned int Entry_ID_CCSID | An integer that represents the CCSID for the entry ID. 
Valid CCSID values are in the range 1 through 65535. 
This field is not used to verify the entry. 


unsigned char | Entry_ID[100] The data that is used to identify this entry in the validation 
| | | list. 


Encrypt_Data 
(Input) 


A pointer to the encrypted data information that is associated with the entry ID. The format of the 
Qsy_Entry_Encr_Data_Info_T structure is as follows: 


int Encr_Data_Len 


unsigned int Encr_Data_CCSID 


The number of bytes of data to be encrypted and 
compared to the encrypted data in the validation list 
entry. Possible values are 1 through 600. 


An integer that represents the CCSID for the data to 
encrypt. Valid CCSID values are in the range 0 through 
65535. This value is not used to verify the entry. 


unsigned char | Encr_Data[600] The data to be encrypted and compared to the encrypted 
data that is found for the specified entry ID in the 


validation list. 


Return Value 


O  QsyVerify ValidationLstEntry() was successful. 
-1 QsyVerifyValidationLstEntry() was not successful. 


The errno global variable is set to indicate the error. 


-2. QsyVerifyValidationLstEntry() was not successful because the encrypted data was incorrect. 


Error Conditions 


If QsyVerify ValidationLstEntry() is not successful, errno indicates one of the following errors: 
3401 [EACCES] 


The current user does not have *USE authority to the validation list object, or does not have 
*EXECUTE authority to the validation list object library. 


3406 [EAGAIN] 

The validation list object is currently locked by another process. 
3454 [EDAMAGE] 

The validation list object is damaged. 
3021 [EINVAL] 

Parameter value is not valid. 
3025 [ENOENT] 

The validation list object was not found. 
3026 [ENOREC] 

Specified entry does not exist. 
3474 [EUNKNOWN] 


Unknown system state. Check the job log for a CPF9872 message. 


Example 


The following example validates the entry for a user named FRED in the validation list object WEBUSRS. 


See Code disclaimer information for information pertaining to code examples. 


#include <qsyvldl.h> 


main () 

{ 
#define VLD_LST "WEBUSRS WEBLIB " 
Qsy_Entry_ID_Info_T entry_info; 
Qsy_Entry_Encr_Data_Info_T encrypt_data; 


entry_info.Entry_ID_Len = 4; 
strncpy (entry_info.Entry_ID, "FRED",entry_info.Entry_ID_Len); 


encrypt_data.Encr_Data_Len = 7; 
strncpy (encrypt_data.Encr_Data,"MSN1TJG", 
encrypt_data.Encr_Data_Len) ; 


if (0 != QsyVerifyValidationLstEntry ((Qsy_Qual_Name_T *) &VLD_LST, 
é&entry_info, 
é&encrypt_data) ) 
perror ("QsyVerifyValidationLstEntry()"); 
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